home *** CD-ROM | disk | FTP | other *** search
/ START Magazine / START VOL 4 NO 1.st / POGO.ARC / POGO.TXT < prev    next >
Encoding:
Text File  |  1985-11-20  |  17.4 KB  |  646 lines
  1. WHAT IS POGO? 
  2.  
  3. Pogo is intended as a language for controlling the motion of animated
  4. creatures.  It also has turtle graphics.  
  5.  
  6. To run Pogo from a command line interpreter type 
  7.     pogo file.pog
  8.  
  9. To run Pogo from the Desktop double-click on POGO.TTP and then type in
  10. the name of the Pogo program to run.  If you don't use a file extension
  11. Pogo will assume .POG.  Pogo programs must be in ASCII format, with one
  12. command per line.
  13.  
  14. You abort any Pogo program by pressing [Control]-C.
  15.  
  16. Pogo syntax resembles C more than anything else, however, it has elements
  17. of BASIC as well.
  18.  
  19. Here is a brief description of the syntax of the language. 
  20.  
  21.  
  22. Comments:
  23.  
  24.     Everything to the right of a semicolon on a line is disregarded.
  25.  
  26. Variables:
  27.  
  28.     Variables must be declared before use.  The syntax is:
  29.         type i,j,k
  30.     or
  31.         type linkcount
  32.     Type is either string or int.  Ints are 16-bit integers. Strings
  33.         can be any length.
  34.  
  35.     Variable names can be up to 512 bytes long or so, but only the
  36.         first 39 characters are significant.  The first letter must be
  37.         alphabetic or an underbar (_).  The next letters can be
  38.         alphanumeric or underbars.  The case is NOT significant.
  39.  
  40.     Variables declared inside a function are local to that function.
  41.         Variables declared inside a creature are local to that creature,
  42.         but their values persist between Evolve()'s of that creature.
  43.         You may not declare a variable inside a function with the same
  44.         name as a variable previously declared on a global level.
  45.  
  46. Arrays:
  47.  
  48.     Arrays are declared like variables with the dimension of the array
  49.     in square brackets after the name.
  50.         int bigarray[500], littlearray[16]
  51.  
  52. Numeric Constants:
  53.  
  54.     Decimal constants.  No floating point.
  55.         5   100   -200
  56.  
  57.     Hexidecimal constants
  58.         0x10  0xFF  0xabc
  59.  
  60.     Character constants - ASCII value of character in single quotes.
  61.         'a'  '*'
  62.  
  63. Numeric Expressions:
  64.  
  65.     The symbols used for various binary and unary operations are
  66.         similar to C, but the precedence is a little better and
  67.         assignments are not considered an expression.
  68.  
  69.     Here is a list of operators grouped by preference with the groups
  70.         in decreasing precedence.
  71.  
  72.     Unary plus and minus, binary not
  73.         +5  -x  ~a
  74.  
  75.     Multiplication, division, modulus binary, left shift, right
  76.         shift, binary and 
  77.                 5*5  a/b  4%3  a<<b  b>>c b&c 
  78.         
  79.         Addition, subtraction, binary or, xor 
  80.                 a+b  x-5  a|b  a^b 
  81.  
  82.         Comparison operators equal to, not equal, greater, less, etc.  
  83.                 a == b    a!= b   a > b   a < b  a >= b  a <= b  
  84.                 hello == "Hi Doc!" 
  85.  
  86.         Logical not 
  87.                 !a 
  88.         Logical and 
  89.                 a && b 
  90.         Logical or 
  91.                 a || b
  92.  
  93.     Comparison and logical operations evaluate to one for true, zero
  94.         for false (though in conditional branches any non-zero is
  95.         considered true).
  96.  
  97.     For convenience the following BASIC keywords have the same effect
  98.         as the corresponding C-like tokens:
  99.  
  100.         EQ  and  ==
  101.         =   and  ==
  102.         OR  and  ||
  103.         AND and  &&
  104.         NOT and  !
  105.         <>  and  !=
  106.  
  107. String Expressions:
  108.  
  109.     A string constant enclosed in quotes 
  110.         "Hello World"
  111.  
  112.     A function returning a string
  113.         StrNum(100)
  114.  
  115.     Two or more strings concatenated with a '+' sign
  116.         filename = "FRAME" + StrNum(i) + ".PC1"
  117.  
  118. Statements:
  119.  
  120.     1. Assignment statements
  121.             var = expression
  122.  
  123.     2. Compound blocks of statements surrounded by curly brackets.
  124.             {
  125.             statement1
  126.             statement2
  127.              ...
  128.             }
  129.  
  130.            Pogo's loop syntax allows you to use single statements within
  131.            a loop or if statement without any brackets:
  132.                         if done
  133.                            break
  134.  
  135.     3. If statements with optional elses.  The statement after the if
  136.        is executed if expression is non-zero.
  137.             if expression
  138.                 statement1
  139.             else
  140.                 statement2
  141.  
  142.             if expression
  143.                 statement
  144.             else if expression
  145.                 {
  146.                 statement1
  147.                 statement2
  148.                 }
  149.  
  150.     4. Loop statements
  151.             loop
  152.                 statement
  153.        (The statement following a loop is normally a compound block
  154.            with a break in it somewhere.)
  155.  
  156.         loop
  157.             {
  158.             statement1
  159.             statement2
  160.             if expression
  161.                 break
  162.             statement3
  163.             }
  164.  
  165.     5. Break statements in loops, fors, whiles, etc..  
  166.        Breaks to end of loop.
  167.  
  168.     6. For statement
  169.         for var = expression to expression [step constant]
  170.             statement
  171.  
  172.         for i = 0 to x
  173.             statement
  174.  
  175.         for i = 100 to 50 step -5
  176.             statement
  177.  
  178.     The for statement checks to make sure the index variable is in
  179.         range at the top of the loop, and adds the step at the end of the
  180.         loop.
  181.  
  182.     7. while statement
  183.             while expression
  184.                 statement
  185.  
  186.        The statement after while is executed until expression is no
  187.        longer true.
  188.  
  189.     8. Goto statements
  190.             goto label
  191.  
  192.        where label is defined elsewhere (within same function) as a
  193.            name followed by a colon.
  194.  
  195.                forever:
  196.                 prints("Hello")
  197.                 goto forever
  198.  
  199.        Labels can be constructed using the same rules as variable
  200.            names.
  201.  
  202.     9.  int and string declaration statements as discussed in the
  203.             variables section. 
  204.  
  205.             int a,b,c
  206.             string filename, month, myname
  207.  
  208.     10. Constant declarations
  209.             constant red = 3
  210.     This attatches a numerical value to a name without the run-time
  211.         overhead of a variable.
  212.  
  213.     11. function declarations.
  214.  
  215.     Function declarations begin with the keyword 'function' or 'to'.
  216.         Next is the type of variable returned by the function; int is
  217.         assumed.  The name of the function follows.  This uses the same
  218.         rules as variable names.  Then you have a list of parameters
  219.         (separated by commas) in parenthesis.  They must each be preceded
  220.         with the word string if they are string parameters.
  221.  
  222.     Here are some examples.
  223.  
  224.             to say_hello()
  225.                {
  226.             prints ("hello")
  227.             }
  228.  
  229.         This function has no parameters and returns zero.
  230.  
  231.                function add2(a,b)
  232.             {
  233.             return(a+b);
  234.             }
  235.  
  236.         This function takes two integer parameters and returns an
  237.                 integer value.
  238.  
  239.               to string numbername(number, string name)
  240.             {
  241.             return( name + strnum(number) )
  242.             }
  243.  
  244.         This function returns a string.  Its first parameter is
  245.                 an integer and its second parameter is a string.
  246.  
  247.  
  248.     12. function usages.
  249.  
  250.             say_hello()
  251.  
  252.             add2(5, 2*c)
  253.  
  254.     13. return statements
  255.  
  256.             return
  257.         or
  258.             return (expression)
  259.  
  260.         If a function 'falls off the end' without a return
  261.                 statement or if the return has no expression zero is
  262.                 returned.
  263.  
  264.     14.  Creature declarations.  Syntactically like function
  265.              declarations without any parameters.
  266.  
  267.                creature name
  268.                {
  269.                statement
  270.                statement...
  271.                }
  272.  
  273.        Function declarations and other creature declarations are not
  274.        allowed inside a creature.  Neither are Evolve() calls.
  275.  
  276.  
  277. Pogo Built-in Functions and Variables
  278.  
  279. Input-oriented functions:
  280.  
  281.     InKey() - Returns ASCII value of key pressed, or 0 if no key
  282.         pressed.
  283.  
  284.     Keyboard() - Returns 16 bit keycode or 0 if no key pressed.
  285.  
  286.     WaitKey() - Waits for key and returns ASCII value.
  287.  
  288.     MouseX() - Returns mouse x position.
  289.  
  290.     MouseY() - Returns mouse y position.
  291.  
  292.     MouseLeft() - True if left button down.
  293.  
  294.     MouseRight() - True if right button down.
  295.  
  296.     Clock()    - Returns current time; 200Hz on ST.
  297.  
  298.     UseJoystick()  -  to transfer from mouse mode to joystick mode.
  299.  
  300.     UseMouse()    - to get back to mouse
  301.  
  302.     Joystick() - returns state of both joysticks.  The high order byte
  303.        contains info on the right joystick, the low order byte info
  304.        on the left joystick.  The hi order bit of each byte contains
  305.        the state of the fire button.  The low order 4 bits contain
  306.        the state of the 4 direction switches.  From lowest to
  307.        highest these are: forward, back, left, right.
  308.  
  309.            The following demo is in the file JOYSTICK.POG:
  310.            
  311.         int i,joy,lastjoy
  312.  
  313.         usejoystick()
  314.         loop
  315.             {
  316.             joy = Joystick()
  317.             if (joy & 0x8  && !(lastjoy & 0x8) )
  318.                 prints("Lefter:  right")
  319.             if (joy & 0x4  && !(lastjoy & 0x4) )
  320.                 prints("Lefter:  left")
  321.             if (joy & 0x2  && !(lastjoy & 0x2) )
  322.                 prints("Lefter:  back")
  323.             if (joy & 0x1  && !(lastjoy & 0x1) )
  324.                 prints("Lefter:  forward")
  325.             if (joy & 0x80  && !(lastjoy & 0x80) )
  326.                 prints("Lefter:  fire")
  327.             if (joy & 0x800  && !(lastjoy & 0x800) )
  328.                 prints("Rightly:  right")
  329.             if (joy & 0x400  && !(lastjoy & 0x400) )
  330.                 prints("Rightly:  left")
  331.             if (joy & 0x200  && !(lastjoy & 0x200) )
  332.                 prints("Rightly:  back")
  333.             if (joy & 0x100  && !(lastjoy & 0x100) )
  334.                 prints("Rightly:  forward")
  335.             if (joy & 0x8000  && !(lastjoy & 0x8000) )
  336.                 prints("Rightly:  fire")
  337.             lastjoy = joy;
  338.             if (inkey())
  339.                 break;
  340.             }
  341. Text Output Functions:
  342.  
  343.     Print(number)
  344.         Prints number in decimal on a line.
  345.     Prints(string)
  346.         Print string and a new line.
  347.     Text(string)
  348.         Print string without a new line.
  349.  
  350. General-Purpose Graphics Functions:
  351.  
  352.     ToText()
  353.         Takes you back to character oriented screen.
  354.     ToGraphics()
  355.         Takes you into graphics mode.
  356.     PutDot(color, x, y)
  357.         Plots a single pixel in color at x, y.
  358.     GetDot(x,y)
  359.         Returns the color at x, y.
  360.     Rectangle(color, x1, y1, x2, y2)
  361.         Draws a rectangle in color with the two corners indicated.
  362.     Disk(x, y, radius, color)
  363.         Draws a solid circle.
  364.     Circle(x, y, radius, color)
  365.         Draws a hollow circle.
  366.     Gtext(color, x, y, string)
  367.         Write text in graphics mode in color at x,y position.
  368.     Gnumber(color, x, y, digits, number)
  369.         Write a number digits wide starting at x,y position.
  370.     Line(color,x1,y1,x2,y2)
  371.         Line in color between two points.
  372.     ClearScreen()
  373.         Fast set screen to 0.
  374.     SetColor(color, r, g, b)
  375.         Set hardware color register color to rgb value.  r g and
  376.                 b go from 0 to 255 
  377.         LoadPic(filename) 
  378.                 Loads in picture in DEGAS Elite .PC1 format, DEGAS .PI1
  379.                 format or Neochrome .NEO format (depending on the suffix
  380.                 of filename).
  381.  
  382.         SavePic(filename) 
  383.                 Save a picture in PC1, PI1 or NEO format.
  384.  
  385. Graphics-oriented constants:
  386.  
  387.     ScreenW
  388.         Width of screen in pixels.
  389.     ScreenH
  390.         Height of screen in pixels.
  391.     Colors
  392.         Number of colors in palette.
  393.     CharW
  394.         Pixel width of character.
  395.     CharH
  396.         Pixel height of character.
  397.  
  398. Screen-Oriented Graphics Functions:
  399.  
  400.     screen = AllocScreen() 
  401.         Sets aside memory for a full screen and return an integer
  402.         handle for it.
  403.     screen = Pscreen() 
  404.         Returns a handle on the physical screen.
  405.     UseScreen(screen) 
  406.         Lets you draw on other screens.
  407.     CopyScreen(sscreen, dscreen) 
  408.         Copies between screens.
  409.     Blit(w,h,sscreen,sx,sy,dscreen,dx,dy) 
  410.         Copies a rectangular area between screens.
  411.     FreeScreen(screen) 
  412.                 Frees up the memory space used by screen.
  413.  
  414. Animation Display Oriented Functions:
  415.  
  416.     PreSwap()     
  417.         Set things up for double buffering. Set drawing pointer
  418.                 off screen.
  419.     Swap() 
  420.         Swap drawing and display screens.
  421.     DeSwap()
  422.         Get out of double-buffering mode.  Set drawing pointer to
  423.                 screen.
  424.     Vsync()    
  425.         Wait for start of vertical blank.
  426.  
  427. "Turtle" Graphics.  Turtle is floating point position.  Not much good for
  428. real-time, but you can do lots of LOGO tricks.
  429.  
  430.     Right(degrees)
  431.         Turn turtle to the right.
  432.     Left(degrees)
  433.         Turn turtle to the left.
  434.     PenUp()
  435.         Don't leave a trail when you move turtle.
  436.     PenDown()
  437.         Start leaving lines behind turtle.
  438.     PenColor(color)
  439.         Change color of turtle's pen.
  440.     Forward(pixels)
  441.         Move turtle in the direction it's pointing.
  442.     Reverse(pixels)
  443.         Back up turtle so many pixels.
  444.  
  445.  
  446. Math functions:
  447.  
  448.     Random(MAX) 
  449.         Returns a random number between 0 and MAX-1.
  450.         Random(100) will generate numbers 0-99
  451.  
  452.     XYangle(x,y)
  453.         Returns the angle (0-360) associated with the x,y
  454.                 offsets.
  455.  
  456.     SquareRoot(x)
  457.         Returns square root (integer you know) of x.
  458.  
  459.     Distance(x1,y1,x2,y1)
  460.         Returns distance between two points.
  461.  
  462.     ArcX(angle,radius)
  463.         Gives you the x position of a ray of radius at angle.
  464.  
  465.     ArcY(angle,radius)
  466.         Gives you the y position of a ray.
  467.  
  468.  
  469. String-Oriented Functions:
  470.  
  471.     StrNum(number)
  472.         Returns an ASCII string version of number.
  473.  
  474.     StrChar(char)
  475.         Returns a string made up of the single character char.
  476.                 a = StrChar('a')
  477.  
  478.     StrLen(string)
  479.         Returns number of characters in string.
  480.  
  481.     CharAt(string, index)
  482.         Returns character at index in string.  (0 is index for 1st
  483.         character of string.)
  484.  
  485.     CharTo(string, index, char)
  486.         Puts char at index in string.
  487.  
  488.     NULL
  489.         Special value for string with no characters.
  490.  
  491.  
  492. Text file reading functions:
  493.  
  494.     f = Fopen(name, mode) 
  495.         string name - the filename
  496.         mode - "w"  if to write
  497.                  - "r"  if to read
  498.         Returns 0 if there's a problem, otherwise the file
  499.                 number.
  500.  
  501.     Fclose(f)
  502.         Close file and free up associated memory.
  503.  
  504.     GetChar(f)  
  505.         Returns a single character or -1 for EOF.
  506.  
  507.     GetWord(f)  
  508.         Returns next word (as separated by white space, but not
  509.                 including any white space) from file f.  Returns NULL at
  510.                 end of file.
  511.  
  512.     GetLine(f)
  513.         Returns next line of file f, including the 
  514.         <cr/lf> character(s).  Returns NULL at end of file.
  515.  
  516.     PutChar(f, char)
  517.         Writes a single character char to file f.
  518.  
  519.     PutString(f, string)
  520.         Writes a string to a file.
  521.  
  522.     PutLine(f, string)
  523.         Writes a string to a file and adds a <cr>.
  524.  
  525.  
  526. CREATURE ORIENTED PROGRAMMING
  527.  
  528. Creature oriented programming is much the same thing as multi-programming
  529. for a non-preemptive multi-tasking system, A creature is a function which
  530. is called once every Evolve() with it's own data, as well as access to
  531. global functions and data.
  532.  
  533. What separates a creature from a function is that local variables are
  534. maintained between calls to Evolve().  Also each instance of a creature
  535. has its own local variables.
  536.  
  537. Creatures have access to the Spawn variables they were created with as
  538. cx, cy, cdx and cdy.  It is recommended that animated creatures actually
  539. use these (implicit local) variables to hold their position and speed as
  540. they move themselves.  The system doesn't actually do much with these
  541. variables other than set aside space for them.  The ClosestCreature(),
  542. and FindDistance() calls depend on cx and cy to reflect the creature's
  543. position.
  544.  
  545.  
  546. Creature Locating Functions:
  547.  
  548.     ClosestCreature(id,x,y) 
  549.         Finds the closest creature to x and y with the exception
  550.                 of id.
  551.             closest = ClosestCreature(cid,cx,cy) 
  552.         would be how one creature could find the id of its
  553.                 closest neighbor.
  554.  
  555.     ClosestT(type,x,y)
  556.         Finds closest creature of a given type.
  557.             food = ClosestType(rabbit,cx,cy)
  558.         where there's a creature rabbit somewhere.
  559.  
  560.     NamedCreature(name)
  561.         Finds id of some creature that has that name, or 0 if
  562.                 none do.
  563.  
  564.     ExistsCreature(id)
  565.         Checks if a creature with id exists.  Can be used in a
  566.                 loop from 1 to 255 to look at all creatures around.
  567.  
  568. Creature Information Functions:
  569.  
  570.     CreatureX(id)
  571.         Returns x position of Mr. id
  572.     CreatureY(id)
  573.         Returns y position.
  574.     CreatureAge(id)
  575.         Returns age of creature #id
  576.     CreatureNewBorn(id)
  577.         True if creature is new to game.
  578.     s = CreatureName(id)
  579.         Returns creature's name string.  Try
  580.                         Prints(CreatureName(id)) 
  581.                 during debugging.
  582.  
  583.     value = Cread(type, var, id)
  584.         (Note: return value necessary.)
  585.         Returns value of another creatures local variable var.
  586.                 Creature id is checked against type during run-time. 
  587.  
  588.     Cwrite(type, var, id, value)
  589.         Writes value to creature #id of type's local variable
  590.                 var.
  591.  
  592.  
  593. Creature life and death oriented functions:
  594.  
  595.     id = Spawn(creature,x,y,dx,dy)
  596.         Make a copy of creature in the evolution table with this
  597.                 initial position.  Id is used to identify this particular
  598.                 copy when calling the other creature oriented functions.
  599.                 The values of x,y,dx and dy are passed to the creature's
  600.                 local cx,cy,cdx and cdy variables.
  601.  
  602.     Evolve()
  603.         Gives all the living creatures a quick run through.
  604.  
  605.     Kill(id)
  606.         Kill the creature with this ID.  Will cause a run-time
  607.                 error if the creature doesn't exist.  Kill(cid) amounts
  608.                 to suicide. 
  609.  
  610.     KillAll()
  611.         Kill all living creatures.  Especially useful when want
  612.                 to restart a game.
  613.  
  614. Creature spawn parameters:
  615.  
  616.     Cx    -current x position.  Polite to update this as you move.
  617.     Cy    -current y position.
  618.     Cdx    -x speed.  This can be socially used for other purposes.
  619.     Cdy     -y speed.  Also not needed by system.
  620.  
  621. Other system-maintained local creature variables:
  622.  
  623.     Cid     - creature id.  Unique among LIVING creatures.
  624.     Cage    - evolution ticks since birth
  625.     Cnew    - true only on birth tick
  626.     Cname    - name of creature
  627.  
  628. Debugging Aids:
  629.  
  630.     Typing ^D will stop your Pogo program and print out a stack trace.  
  631.     Typing dump at the command line, e.g.
  632.         pogo warblers dump
  633.     will get a disassembly in Pogo virtual machine code interspersed
  634.         with the source it was created from.  This may be interesting to
  635.         give you an idea how the Pogo compiler works.
  636.  
  637. Known Bugs
  638.  
  639. o - Using more than 8k of variable space will suddenly and silently crash
  640.     the system.  No large arrays for now!
  641.  
  642. o - You can use an array name without the square brackets in an
  643.     expression with unpredictable results.
  644.  
  645.  
  646.